home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / program / task3210.zip / README.TXT < prev    next >
Text File  |  1996-10-26  |  6KB  |  134 lines
  1. Tasker32 Version 1.00 Documentation.
  2.  
  3. WHAT IS Tasker32?
  4. =================
  5.   Tasker32 is a small library that "Threads", or tasks, your 32 bit protected
  6.   mode DPMI programs so that many portions of the code can run
  7.   simultaneously. A thread is simply a piece of code that is given processor
  8.   time on a regular basis, so the "task" runs x many times per second, or Hz.
  9.  
  10. WHY USE Tasker32?
  11. =================
  12.   Quite simply to speed up program coding and simplify program code. It makes
  13.   the code easier to understand, as all the main code does very little. The
  14.   Tasker32 kernel runs functions that you pass to it at a given frequency
  15.   so the main program thread has to do very litte.
  16.  
  17.   Take the example of a bouncing screen. Using traditional methods of coding,
  18.   the main program thread (that has control when no other threads have been
  19.   called by the Tasker32 kernel) updates the position of the ball in its
  20.   memory then on the screen checking for a bounce. As you add more balls,
  21.   the code gets more complex and messy as the main thread has to update them
  22.   all.
  23.  
  24.   The Tasker32 library overcomes this by the main thread simply assigning the
  25.   task of moving the ball to another thread. Then, whenever the ball is due
  26.   to be updated, the Tasker32 kernel simply calls it for you, regardless of
  27.   what the main thread is doing. To add more balls, simply add more threads.
  28.   Use the same piece of code for each thread if you want to.
  29.  
  30.   An additional advantage is control of how often something happens. In the
  31.   tradional method of single thread programming, it requires complex delays
  32.   to acheive the same speed on all computers. The Tasker32 library overcomes
  33.   this by you simply having to specifiy a frequency that the thread is to
  34.   run.
  35.  
  36. HOW TO USE Tasker32
  37. ===================
  38.   Using Tasker32 is a very simple process. In your main program code, (the
  39.   main thread) simply initialize the tasker with the task_init_tasker()
  40.   function. Its syntax is in TASK32.H.
  41.  
  42.   To add threads is just as easy. Simply use task_add() with paramaters
  43.   pointing to the function to run on a regular basis and the number of times
  44.   per second to run it at. Again, its syntax is in TASK32.H.
  45.  
  46.   All other functions available to the user are in TASK32.H.
  47.  
  48.   To link in the Tasker32 library, include the TASK32.OBJ file on the command
  49.   line of the linker or compiler. See "Compiling The Sample Program" for an
  50.   example. This single object contains all the necessary code for threading.
  51.  
  52. COMPILING THE SAMPLE PROGRAM
  53. ============================
  54.   If you have the registered version of Tasker32, use the command
  55.     BCC32 -WX TEST.C TASK32.OBJ
  56.   to compile the sample program. However, if you have the shareware version
  57.   you must use
  58.     BCC32 -WX -DSHAREWARE TEST.C TASK32.OBJ
  59.   to compile that sample program successfully.
  60.   
  61. THE SHAREWARE VERSION
  62. =====================
  63.   The shareware version has various limitations over the registered version.
  64.   The main limitation is the inability to access the task records in the
  65.   Tasker32 kernel. These contain information on the frequency the task runs
  66.   at, the delay on the system timer, the time left until the task is run
  67.   again and the pointer to the function that is run. This is the task_struct
  68.   structure outlined in TASK32.H.
  69.  
  70.   Also, the task stack is limited to only 128kB, compared the 384kB in the
  71.   registered version. The stack allows standard C and C++ functions to run
  72.   without having errors and probably program crashes. The larger the stack,
  73.   the more functions can be nested.
  74.  
  75.   You are not allowed to distribute programs written with the shareware
  76.   version. See SHARWARE.TXT for details and registration.
  77.  
  78. THE REGISTERED VERSION
  79. ======================
  80.   The registered version has full read-only access to the task records. It
  81.   is made read only deliberatly to prevent the user program accidentaly
  82.   corrupting the area. If, however, it is vital that it is writeable it
  83.   can be defined this way by removing the "const" declaration from the
  84.   TASK32.H file.
  85.  
  86.   A full 384kB stack is provided so you will not run out of room when
  87.   nesting functions.
  88.  
  89.   Best of all, the programs written using Tasker32 can be distributed
  90.   royalty free. See REGISTRD.TXT for details and limitations if you have
  91.   the registered version.
  92.  
  93.   The source code is provided should it need to be specialized.
  94.  
  95. LIMITIATIONS OF Tasker32
  96. ========================
  97.   This is not a "true" multi-tasker, or even a "true" task swapper. The
  98.   kernel expects the called thread to finish executing before the computer
  99.   can continue normal operation. The task is not set up and stays that way
  100.   inside of a possibly infinate loop, such as other more expensive program
  101.   threaders.
  102.  
  103.   This library is will be incompatible with a wide number of DOS DPMI
  104.   extenders. It is, however, compatible with Microsoft(R) Windows(TM).
  105.   If you find an incompatible extender, please mail me with the name, the
  106.   company and the version and I will add it here in future releases.
  107.  
  108.   Incompatible Extenders:
  109.     Quaterdeck QDPMI 1.03
  110.  
  111. DISCLAIMER
  112. ==========
  113.   There is no warranty or gurantee whatsoever provided with this program,
  114.   library and associated files. It is provided as-is. The author cannot and
  115.   will not be held liable in any way for any damaged or loss caused either
  116.   directly or indirectly by this program, library and associated files.
  117.  
  118. CONTACTING THE AUTHOR
  119. =====================
  120.   To contact the author send email to either of
  121.     guyat@xtra.co.nz
  122.     guyat@voyager.co.nz
  123.   Please expect upto a week until reply.
  124.  
  125.   To send snail-mail to the author, the address is
  126.     Guy Thornley
  127.     Katene Road
  128.     RD 15
  129.     Hawera
  130.     New Zealand
  131.   Do not forget air mail if required. All cheques, money, etc. can be sent
  132.   to this address.
  133.  
  134.